home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / c-lang / dbt.lha / DBT / Docs / dbtools.doc
Text File  |  1996-05-17  |  11KB  |  491 lines
  1. TABLE OF CONTENTS
  2.  
  3. dbtools.library/--background--
  4. dbtools.library/AddNode
  5. dbtools.library/AllocString
  6. dbtools.library/CreateBase
  7. dbtools.library/DeleteBase
  8. dbtools.library/DoBaseMove
  9. dbtools.library/FindBase
  10. dbtools.library/GetInt
  11. dbtools.library/GetStr
  12. dbtools.library/GetIntN
  13. dbtools.library/GetStrN
  14. dbtools.library/LoadBase
  15. dbtools.library/LoadBaseID
  16. dbtools.library/SaveBase
  17. dbtools.library/SetInt
  18. dbtools.library/SetStr
  19. dbtools.library/SetIntN
  20. dbtools.library/SetStrN
  21. dbtools.library/--background--                 dbtools.library/--background--
  22.  
  23.     PURPOSE
  24.     The dbtools.library provides an easy way to create saveable
  25.     databases and dynamic structures.
  26.  
  27. dbtools.library/CreateBase                         dbtools.library/CreateBase
  28.  
  29.     NAME
  30.     CreateBase - Create a new list of databases.
  31.  
  32.     SYNOPSIS
  33.  
  34.     database = CreateBase (tags);
  35.     d0               a1
  36.  
  37.     DBase * CreateBase (struct TagItem *);
  38.  
  39.     database = CreateBaseTags (tag1, ...);
  40.  
  41.     DBase * CreateBase (ULONG tag1, ...);
  42.  
  43.     FUNCTION
  44.     This function is used to create a new list of databases.
  45.  
  46.     INPUTS
  47.     tags - Attributes for the bases, terminated with TAG_DONE.
  48.  
  49.     TAGS
  50.     DBT_PrevBase (DBase *) - Pointer to previous base to link to.
  51.  
  52.     DBT_NewBase (ULONG) - ID of the new base to add to the list.
  53.  
  54.     DBT_NewNode (BOOL) - Always TRUE. Creates a new node.
  55.  
  56.     DBT_NewIntData (ULONG) - Long integer to add.
  57.  
  58.     DBT_NewStrData (STRPTR) - Pointer to string.
  59.  
  60.     DBT_OldBase (DBase *) - Ponter to previously created database
  61.         to be continued.
  62.  
  63.     SEE ALSO
  64.     DeleteBase
  65.  
  66.     EXAMPLE
  67.  
  68.     DBase *db;
  69.  
  70.     db = CreateBase (
  71.         DBT_NewBase,        DBT_Text,   /* Create a text base */
  72.             DBT_NewNode,    TRUE,        /* Make a new node */
  73.             DBT_NewStrData, "string1",  /* Add some strings */
  74.             DBT_NewStrData, "string2",
  75.             DBT_NewNode,    TRUE,        /* Add another node */
  76.             DBT_NewStrData, "string3",  /* Add a string */
  77.         DBT_NewBase,        DBT_Phone,  /* Create a phone base */
  78.             /* Add the phone data */
  79.             DBT_NewStrData,    "Beyond the Dawn BBS",
  80.             DBT_NewStrData,    "0923-10002",
  81.             DBT_NewStrData, "",
  82.         TAG_DONE);    /* End of the base */
  83.  
  84.     if(!db) exit();
  85.  
  86.     CreateBase ( DBT_OldBase,    db,    /* Continue on db */
  87.             DBT_NewNode,    TRUE,    /* A new phone node */
  88.             DBT_NewStrData, "Orion BBS",
  89.             DBT_NewStrData,    "0921-13040",
  90.             DBT_NewStrData,    "Datorföreningen Orion",
  91.             TAG_DONE);    /* End */
  92.  
  93.     DeleteBase (db);    /* Free all memory */
  94.     
  95.  
  96. dbtools.library/DeleteBase                         dbtools.library/DeleteBase
  97.  
  98.     NAME
  99.     DeleteBase - Delete a list of databases.
  100.  
  101.     SYNOPSIS
  102.  
  103.     DeleteBase (base);
  104.             a1
  105.  
  106.     DeleteBase (DBase *);
  107.  
  108.     FUNCTION
  109.     This function should be called to free a list of databases.
  110.  
  111.     INPUTS
  112.     base - Pointer to the first database in the list.
  113.  
  114.     SEE ALSO
  115.     CreateBase
  116.  
  117. dbtools.library/DoBaseMove                         dbtools.library/DoBaseMove
  118.  
  119.     NAME
  120.     DoBaseMove - Change the current node of a database.
  121.  
  122.     SYNOPSIS
  123.  
  124.     DoBaseMove (base, pos);
  125.             a1    d1
  126.  
  127.     DeleteBase (DBase *, ULONG pos);
  128.  
  129.     FUNCTION
  130.     This function changes the active node of a database. That is the
  131.     node (record) that will be affected by the functions wich do not
  132.     take node arguments.
  133.  
  134.     INPUTS
  135.     base - Pointer to the database.
  136.     pos  - Position to move to.
  137.            MOVE_NEXT, MOVE_PREV, MOVE_FIRST, MOVE_LAST or
  138.            the number of the record (starting at 1).
  139.  
  140. dbtools.library/GetInt                                 dbtools.library/GetInt
  141.  
  142.     NAME
  143.     GetInt - Get an integer from the current record.
  144.  
  145.     SYNOPSIS
  146.  
  147.     data = GetInt (base, n);
  148.     d0           a1    d1
  149.  
  150.     ULONG GetInt (DBase *, ULONG n);
  151.  
  152.     FUNCTION
  153.     GetInt returns the integer value of the data field n.
  154.     If this field is a string field, 0 will be returned.
  155.  
  156.     INPUTS
  157.     base - Pointer to the database.
  158.     n    - The number of the data field.
  159.  
  160.     SEE ALSO
  161.     GetStr, GetIntN, GetStrN, DoBaseMove
  162.  
  163. dbtools.library/GetStr                                 dbtools.library/GetStr
  164.  
  165.     NAME
  166.     GetStr - Get a string from the current record.
  167.  
  168.     SYNOPSIS
  169.  
  170.     data = GetStr (base, n);
  171.     d0           a1    d1
  172.  
  173.     STRPTR GetStr (DBase *, ULONG n);
  174.  
  175.     FUNCTION
  176.     GetStr returns a pointer to the string in the data field n.
  177.     If this field is a integer field, NULL will be returned.
  178.  
  179.     INPUTS
  180.     base - Pointer to the database.
  181.     n    - The number of the data field.
  182.  
  183.     SEE ALSO
  184.     GetInt, GetIntN, GetStrN, DoBaseMove
  185.  
  186. dbtools.library/GetIntN                               dbtools.library/GetIntN
  187.  
  188.     NAME
  189.     GetIntN - Get an integer from a specified node.
  190.  
  191.     SYNOPSIS
  192.  
  193.     data = GetIntN (base, node, n);
  194.     d0           a1    d1    d2
  195.  
  196.     ULONG GetIntN (DBase *, ULONG node, ULONG n);
  197.  
  198.     FUNCTION
  199.     GetIntN returns an integer value without using DoBaseMove.
  200.     This function will not change the current record, and can
  201.     therefore be used without intefering with Get/Set Int/Str.
  202.     If this field is a string field, 0 will be returned.
  203.  
  204.     INPUTS
  205.     base - Pointer to the database.
  206.     node - The number of the node.
  207.     n    - The number of the data field.
  208.  
  209.     SEE ALSO
  210.     GetStr, GetInt, GetStrN, DoBaseMove, SetStr, SetInt, SetIntN,
  211.     SetStrN
  212.  
  213. dbtools.library/GetStrN                               dbtools.library/GetStrN
  214.  
  215.     NAME
  216.     GetStrN - Get a string pointer from a specified node.
  217.  
  218.     SYNOPSIS
  219.  
  220.     data = GetStrN (base, node, n);
  221.     d0           a1    d1    d2
  222.  
  223.     STRPTR GetStrN (DBase *, ULONG node, ULONG n);
  224.  
  225.     FUNCTION
  226.     GetStrN returns a string pointer without using DoBaseMove.
  227.     This function will not change the current record, and can
  228.     therefore be used without intefering with Get/Set Int/Str.
  229.     If this field is an integer field, NULL will be returned.
  230.  
  231.     INPUTS
  232.     base - Pointer to the database.
  233.     node - The number of the node.
  234.     n    - The number of the data field.
  235.  
  236.     SEE ALSO
  237.     GetStr, GetInt, GetIntN, DoBaseMove, SetStr, SetInt, SetIntN,
  238.     SetStrN
  239.  
  240. dbtools.library/FindBase                             dbtools.library/FindBase
  241.  
  242.     NAME
  243.     FindBase - Find a database.
  244.  
  245.     SYNOPSIS
  246.  
  247.     base = FindBase (base, id);
  248.     d0             a1    d1
  249.  
  250.     DBase *FindBase (DBase *, ULONG id);
  251.  
  252.     FUNCTION
  253.     This function is used to find the first database in a list of
  254.     databases with the specified id.
  255.  
  256.     INPUTS
  257.     base - Pointer to the list of databases.
  258.     id   - ID of the base to find.
  259.  
  260. dbtools.library/LoadBase                             dbtools.library/LoadBase
  261.  
  262.     NAME
  263.     LoadBase - Load a list of databases.
  264.  
  265.     SYNOPSIS
  266.  
  267.     base = LoadBase (file);
  268.     d0             a1
  269.  
  270.     DBase *LoadBase (STRPTR);
  271.  
  272.     FUNCTION
  273.     This function loads a list of databases into memory.
  274.  
  275.     INPUTS
  276.     file - Path and filename.
  277.  
  278.     SEE ALSO
  279.     LoadBaseID
  280.  
  281. dbtools.library/LoadBaseID                         dbtools.library/LoadBaseID
  282.  
  283.     NAME
  284.     LoadBaseID - Load one database.
  285.  
  286.     SYNOPSIS
  287.  
  288.     base = LoadBase (file, id);
  289.     d0             a1    d1
  290.  
  291.     DBase *LoadBase (STRPTR, ULONG);
  292.  
  293.     FUNCTION
  294.     This function loads one database with the right id into memory.
  295.  
  296.     INPUTS
  297.     file - Path and filename.
  298.     id   - ID of the wanted database,
  299.  
  300.     SEE ALSO
  301.     LoadBase
  302.  
  303. dbtools.library/SaveBase                             dbtools.library/SaveBase
  304.  
  305.     NAME
  306.     SaveBase - Save a list of databases.
  307.  
  308.     SYNOPSIS
  309.  
  310.     success = SaveBase (file, base);
  311.     d0            a1      a2
  312.  
  313.     BOOL SaveBase (STRPTR, DBase *);
  314.  
  315.     FUNCTION
  316.     SaveBase saves a list of databases to a file.
  317.     Returns FALSE if failure.
  318.  
  319.     INPUTS
  320.     file - Path and filename.
  321.     base - List of bases.
  322.  
  323.     SEE ALSO
  324.     LoadBaseID
  325.  
  326. dbtools.library/AllocString                       dbtools.library/AllocString
  327.  
  328.     NAME
  329.     AllocString - Copy a string.
  330.  
  331.     SYNOPSIS
  332.  
  333.     str = AllocString (source);
  334.     d0               a1
  335.  
  336.     STRPTR AllocSTring (STRPTR);
  337.  
  338.     FUNCTION
  339.     This function allocates memory with AllocVec, and copies the string
  340.     to the memory.
  341.     FreeVec must be called to free the memory.
  342.  
  343.     INPUTS
  344.     source - String to copy.
  345.  
  346.     SEE ALSO
  347.     exec.library/AllocVec
  348.  
  349. dbtools.library/AddNode                               dbtools.library/AddNode
  350.  
  351.     NAME
  352.     AddNode - Add a node to a database.
  353.  
  354.     SYNOPSIS
  355.  
  356.     node = AddNode (base);
  357.     d0            a1
  358.  
  359.     DNode *AddNode (DBase *);
  360.  
  361.     FUNCTION
  362.     This function will add a new node to the end of the database.
  363.  
  364.     INPUTS
  365.     base - Database to add a new node to.
  366.  
  367.     SEE ALSO
  368.     CreateBase
  369.  
  370. dbtools.library/SetInt                                 dbtools.library/SetInt
  371.  
  372.     NAME
  373.     SetInt - Set an integer in the current record.
  374.  
  375.     SYNOPSIS
  376.  
  377.     success = SetInt (base, n, val);
  378.     d0              a1    d1 d2
  379.  
  380.     BOOL SetInt (DBase *, ULONG n, ULONG val);
  381.  
  382.     FUNCTION
  383.     SetInt sets the data in a field in the current record to the
  384.     specified value. If the field doesn't exist it will be created.
  385.     If this field is a string field, FALSE will be returned.
  386.  
  387.     RETURNS
  388.     Returns TRUE if the data was stored.
  389.     If something went wrong, FALSE is returned.
  390.  
  391.     INPUTS
  392.     base - Pointer to the database.
  393.     n    - The number of the data field.
  394.     val  - The value to set the field to.
  395.  
  396.     SEE ALSO
  397.     SetStr, SetIntN, SetStrN, DoBaseMove
  398.  
  399. dbtools.library/SetIntN                               dbtools.library/SetIntN
  400.  
  401.     NAME
  402.     SetIntN - Set an integer in a node.
  403.  
  404.     SYNOPSIS
  405.  
  406.     success = SetIntN (base, node, n, val);
  407.     d0               a1    d1    d2 d3
  408.  
  409.     BOOL SetIntN (DBase *, ULONG node, ULONG n, ULONG val);
  410.  
  411.     FUNCTION
  412.     SetIntN sets the data in a field in the node to the
  413.     specified value. If the field doesn't exist it will be created.
  414.  
  415.     RETURNS
  416.     Returns TRUE if the data was stored.
  417.     If something went wrong, FALSE is returned.
  418.  
  419.     INPUTS
  420.     base - Pointer to the database.
  421.     n    - The number of the data field.
  422.     node - The node to change.
  423.     val  - The value to set the field to.
  424.  
  425.     SEE ALSO
  426.     SetStr, SetInt, SetStrN, DoBaseMove
  427.  
  428. dbtools.library/SetStrN                               dbtools.library/SetStrN
  429.  
  430.     NAME
  431.     SetStrN - Copy and add a string to a node.
  432.  
  433.     SYNOPSIS
  434.  
  435.     success = SetStrN (base, node, n, str);
  436.     d0               a1    d1    d2 d3
  437.  
  438.     BOOL SetStrN (DBase *, ULONG, ULONG, STRPTR);
  439.  
  440.     FUNCTION
  441.     SetStrN allocates memory and copies the string. The pointer to
  442.     that memory will be stored in the the data field (n). If this
  443.     field already has been set, it will be freed.
  444.     If the field doesn't exist it will be created.
  445.  
  446.     RETURNS
  447.     Returns TRUE if the data was stored.
  448.     If something went wrong, FALSE is returned.
  449.     That would probably be caused by a lack of memory.
  450.  
  451.     INPUTS
  452.     base - Pointer to the database.
  453.     n    - The number of the data field.
  454.     node - The node to change.
  455.     str  - The (NULL terminated) string to copy.
  456.  
  457.     SEE ALSO
  458.     SetStr, SetIntN, SetInt, DoBaseMove
  459.  
  460. dbtools.library/SetStrN                               dbtools.library/SetStrN
  461.  
  462.     NAME
  463.     SetStr - Copy a string to the current record.
  464.  
  465.     SYNOPSIS
  466.  
  467.     success = SetStr (base, n, str);
  468.     d0               a1    d1 d2
  469.  
  470.     BOOL SetStr (DBase *, ULONG, STRPTR);
  471.  
  472.     FUNCTION
  473.     SetStr allocates memory and copies the string. The pointer to
  474.     that memory will be stored in the the data field (n). If this
  475.     field already has been set, it will be freed.
  476.     If the field doesn't exist it will be created.
  477.  
  478.     RETURNS
  479.     Returns TRUE if the data was stored.
  480.     If something went wrong, FALSE is returned.
  481.     That would probably be caused by a lack of memory.
  482.  
  483.     INPUTS
  484.     base - Pointer to the database.
  485.     n    - The number of the data field.
  486.     str  - The (NULL terminated) string to copy.
  487.  
  488.     SEE ALSO
  489.     SetStrN, SetIntN, SetInt, DoBaseMove
  490.  
  491.